The IUP4Eu setup

Any IUP program must follow a set format:

1. open the toolkit, using IupOpen
2. execute one or more calls to IUP routines
3. close the toolkit, using either IupClose or returning the constant IUP_CLOSE

IupOpen takes two parameters, which are generally ignored in IUP4Eu. Each is defaulted to NULL. As it is a function which return one of three values, a programmer should strictly test that the return value is not IUP_ERROR.

IupClose has no parameters and returns VOID.

Between these "parentheses" comes the all-important part of the coding. Several IUP routines, including the various IupVersion functions and a number of Predefined Dialogs are free-standing, but others require that an IupDialog widget exists, as a parent.

An acts as a "top-level window" and is at the heart of all user-defined GUI designs. It has to be visible, through one of the routines, and its very existence requires there to be an event loop, to accept user inputs. The event loop is initiated using IupMainLoop.

So a standard template for an IUP application is:

include iupw.e -- the necessary and sufficient include
IupOpen() -- open the toolkit 
-- describe the design of the GUI 
Ihandle dlg = IupDialog() -- define the top-level window 
IupShow(dlg) -- display the dialog 
IupMainLoop() -- initiate event-handling 
IupClose() -- close the toolkit

Issues to note

The complete IUP toolkit comes in a number of shared libraries (dll, so,...), of which iup.dll or libiup.so is central. The wrapping of IUP functions has been divided into two Open Euphoria modules:

• iup.e - the core module containing mainly the system-based routines
• iupw.e - the widget-based module where the great majority of IUP's widgets are wrapped

A call to the second library includes the first and is sufficient.

All IUP's widgets are stored in structs, linked through a handle, which in the wrapper is denoted as type Ihandle. Each widget type has its own creator function (cf Constructor) and the struct contains all the properties and methods associated with that widget type.

A GUI design in IUP is typically built bottom-up. Consequently the IupDialog definition comes last and is based on the cumulative construction of "inner" widgets, which fall into two categories:

• controls - basic widgets like buttons, labels and texts
• containers - grouping widgets which control the layout and general appearance of the design

Usually, therefore, the IupDialog function takes a parameter, being the "outer" container of the design, but in the cruder template above the default (NULL) value has been used.

A very important aspects of IUP is the simplicity of its sizing and layout arrangements. Some toolkits require the programmer to position and size all widgets, even sometimes assigning positions relative to their container rather than to the outer shell. In IUP, whilst individual sizing is allowed, a typical project may only need size definition of the containing dialog, and often not even then. By using containers within other containers an ideal design is always possible.

The properties of each widget (called attributes in IUP) are set in one of two ways:

• singly, using IupSetAttribute
• multiply, using IupSetAttributes

the latter also having an alias, defined in IUP4Eu, called Ihandle, to indicate, in cases where this is helpful, that IupSetAttributes doubles up as a creator function!

All attributes are assigned using text, conventionally using upper case, for example:

IupSetAttribute(dlg,"TITLE","I am the top-level window")

Unlike in some other GUI toolkits, the X in a standard-style dialog always initiates an IUP_CLOSE value.

Having executed IupClose or otherwise concluded, the toolkit carries out all the necessary garbage collection, so it is not usually necessary to use any form of destructor.

Events linked to other actions are beyond the scope of this introduction but each event (an action in IUP) is associated with a valid "action" property for the widget type and is linked to a user-defined event-handler using the IupSetCallback routine which, superficially, looks like a special form of IupSetAttribute, where the attribute is the action and the assigned value is the event-handler.